For a customer project, I recently needed to take a closer look at best strategies of deploying Chromium settings to thrillions of client machines in a corporate network.
Unfortunately, the information on how to deploy site-wide Chromium
browser policies are a little scattered over the internet and the
intertwining of Chromium preferences and Chromium policies required
deeper introspection.
Here, I'd like to provide the result of that research, namely a list of references
that has been studied before setting up Chromium policies for the customer's proof-of-concept.
Difference between Preferences and Policies
Chromium can be controlled via preferences (mainly user preferences) and
administratively rolled-out policy files.
The difference between preferences and policies are explained here:
https://www.chromium.org/administrators/configuring-other-preferences
The site-admin (or distro package maintainer) can pre-configure the
user's Chromium experience via a master preferences file
(
/etc/chromium/master_preferences). This master preferences file is
the template for the user's preferences file and gets copied over into
the Chromium user profile folder on first browser start.
Note: By studying the recent Chromium code it was found out that
/etc/chromium/master_preferences is the legacy filename of the initial
preferences file. The new filename is
/etc/chromium/initial_preferences. We will continue with
master_preferences here as most Linux distributions still provide the
initial preferences via this file. Whereas the new filename is already
supported by Chromium in openSUSE/SLES, it is not yet support by Chromium
in Debian/Ubuntu. (See Debian bug
#992178).
Difference of 'managed' and 'recommended' Policies
The difference between 'managed' and 'recommended' Chromium policies is
explained here:
https://www.chromium.org/administrators/configuring-other-preferences
Quoting from above URL (last visited 2021/08):
Policies that should be
editable by the user are called "recommended policies" and offer a better
alternative than the master_preferences file. Their contents can be
changed and are respected as long as the user has not modified the value
of that preference themselves.
So, policies of type 'managed' override user preferences (and also lock
them in the Chromium settings UI). Those 'managed' policies are good for
enforcing browser settings. They can be blended in also for existing
browser user profiles. Policies ('managed'
and 'recommended') even get
blended it at browser run-time when modified.
Use case: e.g. for rolling out browser security settings that are
required for enforcing a site-policy-compliant browser user
configuration.
Policies of type 'recommended' have an impact on setting defaults of the
Chromium browser. They apply to already existing browser profiles, if the
user hasn't tweaked with the to-be-recommended settings, yet. Also, they
get applied at browser run-time.
However, if the user has already fiddled with such a to-be-recommended
setting via the Chromium settings UI, the user choice takes precedence
over the recommended policy.
Use case: Policies of type 'recommended' are good for long-term
adjustments to browser configuration options. Esp. if users don't touch
their browser settings much, 'recommended' policies are a good approach
for fine-tuning site-wide browser settings on user machines.
CAVEAT: While researching on this topic, two problematic observations were
made:
- All setting parameters put into the master preferences file
(
/etc/chromium/master_preferences) can't be superceded by
'recommended' Chromium policies. Pre-configured preferences are
handled as if the user has already tinkered with those preferences
in Chromium's settings UI. It also was discovered, that distributors
tend to overload /etc/chromium/master_preferences with their
best practice browser settings. Everything that is not required on
first browser start should be provided as 'recommended' policies,
already in the distribution packages for Chromium .
- There does not seem to be an elegant way to override the package
maintainer's choice of options in
/etc/chromium/master_preferences file via some file drop-in
replacement. (See Debian bug
#992179). So, deploying Chromium
involves post-install config file tinkering by hand, by script or by
config management tools. There is space for improvement here.
Managing Chromium Policy with Files
Chromium supports 'managed' policies and 'recommended' policies. Policies
get deployed as JSON files.
For Linux, this is explained here:
https://www.chromium.org/administrators/linux-quick-start
Note, that for Chromium, the policy files have to be placed into
/etc/chromium. The example on the above web page shows where to place them
for Google Chrome.
Good 'How to Get Started' Documentation for Chromium Policy Setups
This overview page provides a good get-started-documentation on how to
provision Chromium via policies:
https://www.chromium.org/administrators/configuring-policy-for-extensions
First-Run Preferences
It seems, not every setting can be tweaked via a Chromium policy. Esp.
the first-run preferences are affected by this:
https://www.chromium.org/developers/design-documents/first-run-customiza...
So, for tweaking the first-run settings, one needs to adjust
/etc/chromium/master_prefences (which is suboptimal, again see Debian
bug
#992179 for a detailed explanation
on why this is suboptimal).
The required adjustments to
master_preferences can be achieved with the
jq command line tool, here is one example:
# Tweak chromium's /etc/chromium/master_preferences file.
# First change: drop everything that can be provisioned via Chromium Policies.
# Rest of the changes: Adjust preferences for new users to our needs for all
# parameters that cannot be provisioned via Chromium Policies.
cat /etc/chromium/master_preferences \
jq 'del(.browser.show_home_button, .browser.check_default_browser, .homepage)'
jq '.first_run_tabs=[ "https://first-run.example.com/", "https://your-admin-faq.example.com" ]'
jq '.default_apps="noinstall"'
jq '.credentials_enable_service=false .credentials_enable_autosignin=false'
jq '.search.suggest_enabled=false'
jq '.distribution.import_bookmarks=false .distribution.verbose_logging=false .distribution.skip_first_run_ui=true'
jq '.distribution.create_all_shortcuts=true .distribution.suppress_first_run_default_browser_prompt=true'
cat > /etc/chromium/master_preferences.adapted
if [ -n "/etc/chromium/master_preferences.adapted" ]; then
mv /etc/chromium/master_preferences.adapted /etc/chromium/master_preferences
else
echo "WARNING (chromium tweaks): The file /etc/chromium/master_preferences.adapted was empty after tweaking."
echo " Leaving /etc/chromium/master_preferences untouched."
fi
The list of available (first-run and other) initial preferences can be found in Chromium's
pref_names.cc code file:
https://github.com/chromium/chromium/blob/main/chrome/common/pref_names.cc
List of Available Chromium Policies
The list of available Chromium policies used to be maintained in the Chromium wiki:
https://www.chromium.org/administrators/policy-list-3
However, that page these days redirects to the Google Chrome Enterprise
documentation:
https://chromeenterprise.google/policies/
Each policy variable has its own documentation page there. Please note
the "Supported Features" section for each policy item. There, you can
see, if the policy supports being placed into "recommended" and/or
"managed".
This is an example
/etc/chromium/policies/managed/50_browser-security.json file (note that all kinds of filenames are allowed, even files without .json suffix):
"HideWebStoreIcon": true,
"DefaultBrowserSettingEnabled": false,
"AlternateErrorPagesEnabled": false,
"AutofillAddressEnabled": false,
"AutofillCreditCardEnabled": false,
"NetworkPredictionOptions": 2,
"SafeBrowsingProtectionLevel": 0,
"PaymentMethodQueryEnabled": false,
"BrowserSignin": false,
And this is an example
/etc/chromium/policies/recommended/50_homepage.json file:
"ShowHomeButton": true,
"WelcomePageOnOSUpgradeEnabled": false,
"HomepageLocation": "https://www.example.com"
And for defining a custom search provider, I use
/etc/chromium/policies/recommended/60_searchprovider.json (here, I recommend not using DuckDuckGo as DefaultSearchProviderName, but some custom name; unfortunately, I did not find a policy parameter that simply selects an already existing search provider name as the default :-( ):
"DefaultSearchProviderEnabled": true,
"DefaultSearchProviderName": "DuckDuckGo used by Example.com",
"DefaultSearchProviderIconURL": "https://duckduckgo.com/favicon.ico",
"DefaultSearchProviderEncodings": ["UTF-8"],
"DefaultSearchProviderSearchURL": "https://duckduckgo.com/?q= searchTerms ",
"DefaultSearchProviderSuggestURL": "https://duckduckgo.com/ac/?q= searchTerms &type=list",
"DefaultSearchProviderNewTabURL": "https://duckduckgo.com/chrome_newtab"
The Essence and Recommendations
On first startup, Chromium copies
/etc/chromium/master_preferences to
$HOME/.config/chromium/Default/Preferences. It does this only if the
Chromium user profile has'nt been created, yet.
So, settings put into
master_preferences by the distro and the site
or device admin are one-time-shot preferences (new user logs into a
device, preferences get applied on first start of Chromium). Chromium
policy files, however, get continuously applied at browser runtime.
Chromium watches its policy files and you can observe Chromium settings
change when policy files get modified.
So, for continuously provisioning site-wide settings that mostly always
trickle into the user's browser configuration, Chromium policies should
definitely be preferred over
master_preferences and this should be
the approach to take.
When using Chromium policies, one needs to take into account that
settings in
/etc/chromium/master_preferences seem to have
precedence over 'recommended' policies. So, settings that you want to
deploy as recommended policies
must be removed from
/etc/chromium/master_preferences.
Essentially, these are the recommendations extracted from all the above
research and information for deploying Chromium on enterprise scale:
- Everything that's required at first-run should go into
/etc/chromium/master_preferences.
- Everything that's not required at first-run should be removed from
/etc/chromium/master_preferences.
- Everything that's deployable as a Chromium policy should be deployed as a policy (as
you can influence existing browser sessions with that, also long-term)
- Chromium policy files should be split up into several files.
Chromium parses those files in alpha-numerical order. If policies occur
more than once, the last policy being parsed takes precedence.
Feedback
If you have any feedback or input on this post, I'd be happy to hear it. Please get in touch via the various channels where I am known as sunweaver (OFTC and libera.chat IRC, [matrix], Mastodon, E-Mail at debian.org, etc.). Looking forward to hearing from you. Thanks!
light+love
Mike Gabriel (aka sunweaver)
Ten years ago 
Mr. Robot is set in the year 2015, and I was surprised that Iceweasel was being used, which led me to search for that post where I announced Firefox was back and realizing that we were close to the 5 years mark. Well, we are at the 5 years mark now.
I d normally say time flies, but it turns out it hasn t flown as much as I thought it did. I wonder if the interminable pandemic is to blame for that.
Like 